/*
 *  Copyright 2005 Blandware (http://www.blandware.com)
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */
package com.blandware.atleap.persistence.forum;

import com.blandware.atleap.common.util.PartialCollection;
import com.blandware.atleap.common.util.QueryInfo;
import com.blandware.atleap.model.forum.Forum;
import com.blandware.atleap.model.core.ContentLocale;
import com.blandware.atleap.persistence.core.DAO;

import java.util.Map;

/**
 * <p>DAO for forums.</p>
 * <p><a href="ForumDAO.java.html"><i>View source</i></a></p>
 *
 * @author Roman Puchkovskiy <a href="mailto:roman.puchkovskiy@blandware.com">
 *         &lt;roman.puchkovskiy@blandware.com&gt;</a>
 * @version $Revision: 1.3 $ $Date: 2006/10/31 11:55:52 $
 */
public interface ForumDAO extends DAO {

    // ~ CRUD Methods ================================================================

    /**
     * Creates new forum.
     *
     * @param forum forum to create
     * @param parent forum parent
     * @param language language of this forum
     * @param linkedObjects map of pairs <code>uri -&gt; object<code>, which
     * link URI in the annotation to corresponding object (resource or page) if
     * it exists
     * @return ID of created forum
     */
    public Long createForum(Forum forum, Forum parent, ContentLocale language,
                            Map linkedObjects);

    /**
     * Retrieves forum with given ID.
     *
     * @param forumId forum ID
     * @return forum with given ID
     */
    public Forum retrieveForum(Long forumId);

    /**
     * Updates a forum.
     *
     * @param forum forum to update
     * @param parent parent forum
     * @param linkedObjects map of pairs <code>uri -&gt; object<code>, which
     * link URI in the annotation to corresponding object (resource or page) if
     * it exists
     */
    public void updateForum(Forum forum, Forum parent, Map linkedObjects);

    /**
     * Deletes a forum.
     *
     * @param forum forum to delete
     */
    public void deleteForum(Forum forum);

    // ~ Additional methods ================================================================

    /**
     * Retrieves filtered/sorted collection of forums
     *
     * @param queryInfo Object that contains information about how to filter
     * and sort data
     * @return Collection of forums
     */
    public PartialCollection listForums(QueryInfo queryInfo);

    /**
     * Searches for duplicates. Returns true if there is one or more forums
     * with another ID, but which have the same title and parent
     *
     * @param forum             Forum to find duplicates for
     * @param parentId          ID of parent
     * @return whether this forum has duplicates
     */
    public boolean hasDuplicates(Forum forum, Long parentId);

    /**
     * Changes a forum position so that it becomes one position higher or lower.
     *
     * @param forum what forum to move
     * @param up if true, forum is moved up, else down
     */
    public void moveForum(Forum forum, boolean up);

    /**
     * Returns least and most positions of forum which parent has given ID. If
     * parentId is <code>null</code>, then root forums are considered.
     *
     * @param parentId ID of forum which children will be considered
     * @return two-element array: least and most occupied positions
     */
    public Integer[] getFirstLastOccupiedPositions(Long parentId);
}
